今天又來到我們相對輕鬆、好理解的話題時間～

在軟體開發過程中，有些版本是特別重要的：
第一個可以 Demo 的版本、成功上線的版本，或是修掉一個超大 Bug 的版本。

這些關鍵時刻，我們都希望在 Git 歷史貼上「便利貼」，方便日後快速回顧或切換。

這就是 git tag 的用途 —— 標記重要時刻，幫你的 Commit 貼上「里程碑標籤」。

什麼是 git tag？

在 Git 裡，每一個 Commit 都有一組長長的雜湊值（SHA-1）。但如果要回到某個版本時，總不能每次都輸入一堆亂碼吧？

想像你的 commit 是專案的日記，每一行都是每天的進度，但當你完成一個重要版本（例如 v1.0 發佈、重要里程碑完成），你可能想快速找到它。

這時候，git tag 就派上用場了：

• 給 commit 一個「名字」或「版本號」
• 標記重要版本、發佈點或里程碑
• 方便日後回溯、部署或打包

它能幫某個 Commit 建立一個「人類可讀的名字」
像是 v1.0.0 或 release-2025-10-01 ，讓你能快速定位到那個版本。

簡單來說：tag = 歷史上的便利貼。

Tag 的類型

1️⃣ 輕量標籤（Lightweight Tag）

• 就像在 commit 上貼一個小紙條或書籤
• 只儲存 commit ID，不包含額外訊息
• 適合快速標記或臨時用途

建立方式：

git tag v1.0.0

2️⃣ 附註標籤（Annotated Tag）

• 包含 commit ID、作者、日期、標籤訊息，甚至 GPG 簽章（可選）
• 適合正式發佈版本
• 訊息可描述版本特性、發佈內容

建立方式：

git tag -a v1.0.0 -m "初次上線版本"

執行後就會記錄完整資訊，比較適合正式的版本管理。

• -a 表示 annotated
• -m 後面是描述訊息

指定 commit 建立 tag

若想標記不是最新的 commit，可以指定 commit hash：

git tag -a v0.9 <commit-hash> -m "Beta 版本"

基本操作

查看 tag

git tag

這會列出目前所有的 tag。

搜尋特定格式的 tag

git tag -l "v1.*"

這會列出符合特定格式的 tag。

查看 tag 詳細資訊

git show v1.0

標籤詳細資訊（annotated tag 才有），可以看到：

• Tag 指向哪個 commit
• 作者與日期
• 標籤訊息

切換到標籤

git checkout v1.0.0

注意：會進入 detached HEAD 狀態，表示不在任何分支上，而是停留在該 commit。

推送 tag 到遠端

建立 tag 只是本地動作，想讓團隊也看到，需要推送：

# 推送單一 tag
git push origin v1.0

# 推送所有 tag
git push origin --tags

注意：推送前確認 tag 指向正確的 commit。

小技巧

• tag 適合 發佈版本 或 里程碑標記，不要隨意對每個 commit 都貼

• 如果發現 tag 指錯 commit，可以刪掉再重新建立：

  git tag -d v1.0           # 刪除本地 tag
  git push origin :refs/tags/v1.0  # 刪除遠端 tag
  

• 搭配 CI/CD 或 release workflow，自動化部署時會用到 tag

小挑戰 💪

1. 建立輕量 tag v0.1 在最新 commit
2. 建立附註 tag v1.0 並加上描述訊息
3. 嘗試推送 tag 到遠端，並確認團隊可以看到
4. 用 git show 查看 tag 詳細資訊
5. 嘗試刪除本地及遠端 tag，理解操作流程

小結

• git tag 是專案歷史的便利貼，標記重要 commit
• 輕量 tag 快速、簡單；附註 tag 詳細、適合發佈
• 推送到遠端後，團隊也能看到你的重要版本
• 善用 tag，能清楚管理專案版本，回顧歷史時快速找到關鍵時刻

「每天 commit 是日記，tag 是貼在日記上的便利貼」
只要掌握 tag，你就能在專案歷史中快速找到關鍵時刻